---
title: "Triggers"
---

## Overview

Triggers in Keep Workflow Engine define **when a workflow is executed**. Triggers are the starting point for workflows and can be configured to respond to a variety of events, conditions, or schedules.

A workflow can have one or multiple triggers, and these triggers determine the specific circumstances under which the workflow is initiated. Examples include manual invocation, time-based schedules, or event-driven actions like alerts or incident updates.

Triggers are defined under the `triggers` section of a workflow YAML file. Each trigger has a `type` and optional additional configurations or filters.

## Supported Trigger Types

### Manual Trigger

Used to execute workflows on demand.

```yaml
triggers:
  - type: manual
```

### Interval Trigger

Runs workflows at a regular time.

```yaml
triggers:
  - type: interval
    # Run every 5 seconds
    value: 5
```

### Alert Trigger

Executes a workflow when an alert is received.

```yaml
triggers:
  - type: alert
```

<Note>
  If no filters or CEL expressions are specified, the workflow will be executed
  for every alert that comes in.
</Note>

### Filtering Alerts

There are two ways to filter alerts in Keep:

#### 1. CEL-based Filtering (Recommended)

Keep uses [Common Expression Language (CEL)](https://github.com/google/cel-spec/blob/master/doc/langdef.md) for filtering alerts. CEL provides a powerful and flexible way to express conditions using a simple expression language.

```yaml
triggers:
  - type: alert
    cel: source.contains("datadog") && severity == "critical"
```

Common CEL patterns:

- String matching: `source.contains("prometheus")`
- Exact matching: `severity == "critical"`
- Multiple conditions: `source.contains("datadog") && severity == "critical"`
- Pattern matching: `name.contains("error") || name.contains("failure")`
- Complex conditions: `(source.contains("datadog") && severity == "critical") || (source.contains("newrelic") && severity == "error")`

You can test and experiment with CEL expressions using the [CEL Playground](https://playcel.undistro.io/).

#### 2. Legacy Filtering (Deprecated)

The old filtering mechanism is deprecated but still supported for backward compatibility. It uses a list of key-value pairs with optional regex patterns.

```yaml
triggers:
  - type: alert
    filters:
      - key: severity
        value: critical
      - key: source
        value: datadog
      - key: service
        value: r"(payments|ftp)"
```

### Incident Trigger

Runs workflows when an incident is created, updated, or resolved.

```yaml
triggers:
  - type: incident
    on:
      - create
      - update
```

### Field Change Trigger

Executes a workflow when specific fields in an alert change, such as status or severity.

```yaml
triggers:
  - type: alert
    only_on_change:
      - status
```

## Summary

Triggers are a powerful way to control the execution of workflows, ensuring that they respond appropriately to manual actions, schedules, or events. By leveraging CEL expressions or filters, workflows can be fine-tuned to execute only under specific conditions.

For more information about CEL expressions, refer to the [CEL Language Definition](https://github.com/google/cel-spec/blob/master/doc/langdef.md) and experiment with expressions in the [CEL Playground](https://playcel.undistro.io/).
